---
title: "Introduction"
description: "Build MCP servers with mcp-use server framework"
icon: "list-start"
---

# MCP Server

**mcp-use** has a complete MCP server framework implementation for TypeScript. 
It improves the official Model Context Protocol SDK with support for Edge Runtime, ChatGPT Apps SDK and MCP-UI. In addition, it supports all official MCP features and achieves a conformance score of 100/100 based on the official MCP Conformance Tests.

## Key Features

- **Full MCP compatibility**: MCP servers built with mcp-use are 100% compatible with the MCP specs.
- **Apps SDK & MCP-UI support**: UI widgets are compatible with Apps SDK for ChatGPT and MCP-UI resources. [UI Widgets](/typescript/server/ui-widgets).
- **Edge runtime support**: Built-in Edge runtime support
- **Built-in Inspector**: An handy MCP inspector is launched for you to test you MCP server.
- **One command to get started**: Use `npx create-mcp-use-app` command to scaffold a complete MCP server.

## Installation

### Using create-mcp-use-app (recommended)

The easiest way to get started is to use the `create-mcp-use-app` command, which scaffolds a complete MCP server project with all necessary configuration:

<CodeGroup>
```bash npm
npx create-mcp-use-app my-mcp-server
cd my-mcp-server
npm run dev
```

```bash pnpm
pnpm create mcp-use-app my-mcp-server
cd my-mcp-server
pnpm dev
```

```bash yarn
yarn create mcp-use-app my-mcp-server
cd my-mcp-server
yarn dev
```
</CodeGroup>

This command will create a new MCP server with:
- A complete TypeScript MCP server project structure.
- Example MCP Tools and Resources to get you started.
- Example UI Widgets React components in `resources/` folder exposed as tools and resources in Apps SDK for ChatGPT and MCP-UI format.
- Pre-configured build tools and dev server.
- All necessary dependencies installed.
- MCP Inspector to test your server.

### Project Structure

After creation, your project will have this structure:

```
my-mcp-server/
├── resources/
│   └── component.tsx  # React widgets for Apps SDK and MCP-UI
├── index.ts           # MCP server entry point, you can add tools and rest endpoints here
├── package.json
├── tsconfig.json
└── README.md
```

### Running Your MCP Server

Commands:

<CodeGroup>
```bash yarn
yarn dev   # start the development server
yarn build # build the server
yarn start # start the production server
yarn deploy # deploy the server to mcp-use cloud
```
```bash npm
npm run dev   # start the development server
npm run build # build the server
npm run start # start the production server
npm run deploy # deploy the server to mcp-use cloud
```
```bash pnpm
pnpm dev   # start the development server
pnpm build # build the server
pnpm start # start the production server
pnpm deploy # deploy the server to mcp-use cloud
```
</CodeGroup>

When you run your MCP server, it will be available at:
- **MCP Endpoint**: `http://localhost:3000/mcp` - For MCP client connections
- **MCP Inspector**: `http://localhost:3000/inspector` 


### Deploy Your MCP Server
You can deploy your MCP server on any platform. Build your MCP server with `npm run build` and start the production server with `npm run start`.
Or you can deploy it on [mcp-use Cloud](https://mcp-use.com).
For detailed instructions, see the [Deploy Your Server](/typescript/server/deployment-mcp-use) guide.




### Next Steps

- [Core features](/typescript/server/tools): Learn how to create MCP tools, prompts and resources.
- [UI Widgets](/typescript/server/ui-widgets): Expose UI components to chat clients compatible with ChatGPT Apps SDK and MCP-UI.
- [Configuration](/typescript/server/configuration): Advanced configuration and deployment options.
- [Deploy Your Server](/typescript/server/deployment-mcp-use) - Deploy to production with one command


### Manual Installation

If you prefer to set up manually or add mcp-use to an existing project, install the package via npm:

<CodeGroup>
```bash npm
npm install mcp-use
```
```bash pnpm
pnpm add mcp-use
```
```bash yarn
yarn add mcp-use
```
</CodeGroup>


## Example server file

The easiest way to start is with `create-mcp-use-app`, which provides a working example. After running the scaffold command above, your server is ready to go!

For manual setup, here's a minimal example:

```typescript
import { MCPServer, text, object } from 'mcp-use/server'
import { z } from 'zod'

// Create server instance
const server = new MCPServer({
  name: 'my-mcp-server',
  version: '1.0.0',
  description: 'My first MCP server',
})

// Define a simple tool
server.tool({
  name: 'greet',
  description: 'Greet someone by name',
  schema: z.object({
    name: z.string().describe('The name of the person to greet'),
  })
}, async ({ name }) => 
    text(`Hello, ${name}! Welcome to MCP.`)
)

// Define a resource
server.resource({
  name: 'config',
  uri: 'config://settings',
  description: 'Server configuration',
}, async () => 
    object({
      theme: 'dark',
      language: 'en'
    })
)

// Start the server
await server.listen(3000)
```

When you run this server, it will be available at:
- **MCP Endpoint**: `http://localhost:3000/mcp` - For MCP client connections
- **Inspector UI**: `http://localhost:3000/inspector` - Development and testing interface

## Architecture Overview

The mcp-use server framework is designed around a modular architecture that seamlessly integrates MCP protocol features with Express.js flexibility. Understanding this architecture helps you build powerful, production-ready MCP servers.

The framework is built on six fundamental components that work together:

### **Server Instance**
The main `MCPServer` class created via `new MCPServer()`. It orchestrates all MCP functionality, manages the Express application, and handles client connections.

**Learn more**: See [Configuration](/typescript/server/configuration) for server setup options.

### **Tools**
Executable functions that MCP clients can invoke with typed parameters. Tools perform actions, fetch data, or trigger operations and return structured results.

**Learn more**: [Tools Guide →](/typescript/server/tools)

### **Resources**
Static or dynamic content accessible via URIs. Resources can be configuration files, documentation, data feeds, or any content that clients need to read.

**Learn more**: [Resources Guide →](/typescript/server/resources)

### **Prompts**
Reusable, parameterized templates for AI model interactions. Prompts standardize how your server generates context for LLM conversations.

**Learn more**: [Prompts Guide →](/typescript/server/prompts)

### **UI Widgets**
Rich, interactive React components that render in chat clients. Widgets are automatically registered from your `resources/` folder and work with both ChatGPT Apps SDK and MCP-UI.

<img src="./images/apps-sdk-widget.png" alt="Apps SDK UI Widget Example" style={{maxWidth: '600px', borderRadius: '8px', margin: '1rem 0', boxShadow: '0 2px 12px rgba(0,0,0,0.08)'}} />

**Key features:**
- **Automatic Registration**: Drop `.tsx` files in `resources/` and they become MCP tools
- **Zero Boilerplate**: No manual `server.tool()` or `server.uiResource()` calls needed
- **Hot Module Replacement**: Changes reflect instantly during development
- **Type-Safe Props**: Zod schemas provide full TypeScript type safety
- **Interactive**: Widgets can call tools, manage state, and respond to user actions

**Learn more**: [UI Widgets Guide →](/typescript/server/ui-widgets)

### **Custom Endpoints Integration**
Full Express.js and Hono functionality for custom routes, middleware, authentication, static file serving, and more. The server instance is also an Express app.

```typescript
// Add custom routes
server.get('/api/mango', (req, res) => {
  res.json({ fruit: 'mango' })
})
```

**Learn more**: [API Reference →](/typescript/server/api-reference)


## McpServer API

The `McpServer` class provides a clean, chainable API:

```typescript
class McpServer {
  // MCP Protocol Methods
  tool(definition: ToolDefinition): this
  resource(definition: ResourceDefinition): this
  resourceTemplate(definition: ResourceTemplateDefinition): this
  prompt(definition: PromptDefinition): this
  uiResource(definition: UIResourceDefinition): this
  
  listen(port?: number): Promise<void>

  // Hono/Express proxy - all HTTP methods available
  // Examples: get(), post(), use(), static(), route()
}
```

**Additional Features:**
- **[OAuth Authentication](/typescript/server/authentication)**: Configure OAuth providers for secure authentication
- **[Sampling](/typescript/client/sampling)**: Request LLM completions from the client during tool execution
- **[Notifications](/typescript/server/notifications)**: Send real-time notifications to connected clients
- **[Inspector UI](/inspector)**: Interactive debugging interface automatically served at `/inspector` endpoint

## Next Steps

<CardGroup cols={3}>
  <Card title="Tools" icon="wrench" href="/typescript/server/tools">
    Build executable functions with parameters and validation
  </Card>
  <Card title="Resources" icon="folder-open" href="/typescript/server/resources">
    Expose static and dynamic content via URI-based resources
  </Card>
  <Card title="Prompts" icon="message-square" href="/typescript/server/prompts">
    Create reusable prompt templates for AI interactions
  </Card>
  <Card title="UI Widgets" icon="palette" href="/typescript/server/ui-widgets">
    Build interactive React components with auto-registration
  </Card>
  <Card title="Configuration" icon="cog" href="/typescript/server/configuration">
    Configure your server for production deployment
  </Card>
  <Card title="Deploy to Production" icon="rocket" href="/typescript/server/deployment-mcp-use">
    Deploy your server to mcp-use Cloud with one command
  </Card>
</CardGroup>

